Chrome Bridge + CLI + Skills 工作流自动化

核心观点

需要借助已登录浏览器上下文抓取数据时，最稳定的结构不是让 Codex 或插件直接承载业务逻辑，而是把系统拆成三层：Chrome extension 只负责进入目标 tab 并执行固定 fetch，常驻 server + CLI 只负责传输和命令提交，具体接口选择、参数拼装、解析、过滤和总结都沉淀到调用方 skill。

这样做可以同时解决三类问题：

• 登录态和 Cookie 由真实 Chrome tab 提供，不需要在 Codex 里复制认证信息。
• transport 层保持通用，不绑定具体业务系统。
• 业务自动化可以以 skill 的形式复用、测试、安装和迭代。

来源

• 项目：<local-project-path>
• 通用 transport skill：skills/browser-fetch-bridge/SKILL.md
• 告警总结 skill：skills/alert-summary/SKILL.md
• CLI：cli/browser-fetch-bridge.js
• Server：server/service.js、server/ws-bridge.js
• Chrome extension：extension/background.js、extension/popup.*

本次沉淀出的边界

层级	责任	不负责
Chrome extension	连接本地 proxy、按调用方传入规则匹配或创建 tab、注入固定 fetch helper、返回原始 response	不理解具体业务系统，不做接口选择，不解析业务结果，不执行任意 JS
Resident server	常驻 HTTP/WebSocket 服务，提供 /status、/fetch，维护一条 extension WebSocket 连接	不做 MCP，不承载业务逻辑，不保存 tab 状态
CLI	向 server 提交 status 和 fetch 命令，支持 payload file、token、host、port、timeout	不拼业务 payload，不处理业务结果
通用 skill	告诉 Codex 如何使用 CLI 通过浏览器上下文 fetch	不绑定具体平台
业务 skill	根据业务 API 文档组织 payload，调用通用 fetch，解析并产出报告	不修改 transport 层

架构链路

Codex / calling skill
  ↓ writes payload JSON
CLI: browser-fetch-bridge fetch --payload-file
  ↓ HTTP POST /fetch
resident server
  ↓ WebSocket request
Chrome extension
  ↓ tabUrlPattern match, or create tabUrl
target Chrome tab
  ↓ injected fixed fetch helper
business API
  ↓ raw response text
caller parses, groups, summarizes, writes report

与 Codex Chrome skills 的对比

Codex 内置的 Chrome skill 更像“浏览器操作员”：它适合接管真实 Chrome tab，阅读页面、点击、输入、截图、处理扩展安装或登录态检查。Browser Fetch Bridge 更像“浏览器上下文 API 通道”：它不操作页面 UI，只借用目标 tab 的登录态发起固定 fetch，并把原始 HTTP response 交给调用方解析。

维度	Codex Chrome skill	Browser Fetch Bridge
核心能力	控制用户 Chrome，进行可视化页面操作、DOM/截图读取、点击输入	通过 CLI 向目标 tab 注入固定 fetch，返回 raw response
入口	Codex 直接使用 Chrome 浏览器控制能力	Codex 调用 browser-fetch-bridge CLI，CLI 再转发到 extension
最适合	安装/修复扩展、检查页面状态、登录确认、表单流程、截图验证、需要看见页面的任务	已知接口、批量查询等需要浏览器 Cookie 但输出要结构化的任务
数据形态	页面可见内容、DOM、截图、交互结果	HTTP status、headers、text、url、ok
自动化稳定性	受页面布局、交互状态、tab 控制生命周期影响	受接口契约影响，更适合脚本化和回归测试
业务逻辑位置	通常在当次 Codex 操作中临时判断	固化在调用方 skill 或业务脚本中
安全边界	不应读取 cookies/local storage/session store；敏感提交需要确认	不暴露任意 JS，只允许固定 fetch；本地 token 保护 HTTP/WebSocket
不适合	已有稳定 API/CLI 时，不应反复用页面自动化模拟批量查询	需要点击、截图、页面视觉判断、登录/CAPTCHA/人工确认的流程

选择规则：

• 需要“看见页面并操作页面”时，用 Codex Chrome skill。
• 已经知道接口和参数，只需要借用 Chrome 登录态批量拿数据时，用 Browser Fetch Bridge。
• 需要先发现接口时，可以先用 Chrome skill 打开页面、观察 Network 或页面行为，再把稳定接口沉淀进业务 skill，通过 Browser Fetch Bridge 执行。
• 需要修复 extension、确认 popup 状态、处理用户登录或权限提示时，用 Chrome skill。
• 需要重复跑同一类排查、生成报告或被其他 skill 调用时，用 Browser Fetch Bridge。

因此两者不是替代关系，而是分工关系：Chrome skill 负责探索和人工态浏览器操作，Browser Fetch Bridge 负责把已经明确的浏览器上下文 fetch 流程变成可复用自动化。

关键实现决策

1. Extension 不绑定业务系统

最初目标是支持告警排查，但 extension 不应该知道具体业务系统的接口、参数、过滤规则或业务标识。最终约束为：

• 调用方传入 tabUrl 和 tabUrlPattern。
• extension 只用 tabUrlPattern 查找已有 tab。
• 未命中时用 tabUrl 新建 inactive tab。
• 不保留 tab.id，避免 tab 生命周期和业务状态耦合。
• 注入函数只做 fetch，并固定使用 credentials: "include"。

这使同一个 bridge 可以复用到告警平台、监控平台、内部后台或其他需要浏览器登录态的系统。

2. Server 移除 MCP，改为常驻服务

MCP 更适合工具协议暴露，但这里需要一个长期存在的本地 proxy，供 extension 持续连接。最终结构是：

• server/service.js 作为常驻入口。
• server/ws-bridge.js 同时处理 HTTP 和 WebSocket。
• HTTP endpoint：
  • GET /status
  • POST /fetch
• WebSocket 只面向 Chrome extension。
• 所有 HTTP/WebSocket 调用都要求 bridge token。

Codex 不直接调用 MCP tool，而是通过 CLI 向常驻服务提交命令。

3. CLI 是 Codex 和 server 之间的稳定契约

CLI 保持两个命令：

node <local-project-path>/cli/browser-fetch-bridge.js status
node <local-project-path>/cli/browser-fetch-bridge.js fetch --payload-file /path/to/payload.json

默认参数：

参数	默认值
host	127.0.0.1
port	37891
token	<bridge-token>
timeout	30000ms

CLI timeout 和 extension 自动重连间隔都统一到 30s，避免 Codex 侧检查过早失败，也避免 extension 断开后长时间不可用。

4. Skill 分成 transport skill 和业务 skill

通用 skill 只暴露 transport 能力：

• 先检查 status。
• 不可用时提示启动 server。
• 写 payload JSON。
• 调用 CLI fetch。
• 返回原始响应，解析交给调用方。

业务 skill 再负责具体逻辑。本次告警总结 skill 的流程是：

1. 通过 bridge 检查 server 和 extension 连接状态。
2. 按 API 文档或 example/README.md 中的参数组织请求。
3. 查询告警列表。
4. 查询每条告警 ID。
5. 去重后查询详情。
6. 针对日志型告警抽取“抽样日志”。
7. 汇总为 业务标识 / 指标 / 详情 表格。
8. 输出本地 Markdown 报告。

Payload 模板

{
  "tabUrl": "https://example.internal/app",
  "tabUrlPattern": "https://example.internal/*",
  "request": {
    "url": "/api/items",
    "method": "GET",
    "headers": {
      "accept": "application/json, text/plain, */*"
    }
  },
  "timeoutMs": 30000
}

约束：

• tabUrlPattern 只用于匹配已有 tab。
• tabUrl 只用于未命中时新建 tab。
• request.url 可以是绝对 URL，也可以是相对 URL。
• 相对 URL 会按目标 tab 的 location.href 解析。
• request.body 必须是字符串；JSON body 由调用方序列化。

新增一个业务自动化 skill 的流程

1. 定义业务目标和输出物

先明确结果形态，而不是先写接口调用：

• 要查什么时间范围？
• 要按什么维度聚合？
• 每条详情需要保留哪些字段？
• 是否需要抽样日志、traceId、链接或原始文本？
• 输出是 Markdown、CSV、JSON 还是直接回复？

这一步属于业务 skill，不进入 extension/server/CLI。

2. 从接口文档组织 fetch payload

接口参数来源可以是：

• example/README.md
• 业务系统前端请求参数
• 已有 curl/HAR
• 浏览器 Network 面板

把每个接口封装成调用方脚本里的 payload builder，保持所有业务参数都在调用方侧。

3. 先跑通连接状态

node <local-project-path>/cli/browser-fetch-bridge.js status

检查点：

• server 可访问。
• extension connected 为 true。
• 若 extension 断开，打开 popup 手动 Reconnect 或等待 30s 自动重连。

4. 通过 CLI 发起浏览器上下文 fetch

node <local-project-path>/cli/browser-fetch-bridge.js fetch --payload-file /tmp/payload.json

调用方只假设返回 raw response：

• status
• statusText
• headers
• text
• ok
• url

不要让 bridge 帮忙解释业务含义。

5. 在调用方脚本中解析、聚合、输出

推荐输出结构：

输入范围
  ↓
接口调用统计
  ↓
聚合表格
  ↓
逐条详情
  ↓
异常 / 未取到详情列表
  ↓
下一步建议

告警场景中，最终报告至少包含：

列	含义
业务标识	业务标识
指标	告警指标或来源
详情	代表性告警内容、状态、优先级、样本日志

6. 给 skill 写清楚边界和命令

业务 skill 必须写明：

• 什么时候触发。
• 依赖 browser-fetch-bridge。
• 默认时间范围和参数。
• 是否允许输出外部链接。
• 输出文件位置。
• 遇到 server/extension 不可用时怎么处理。
• 哪些逻辑不允许沉到 extension/server。

7. 写测试固定契约

至少覆盖：

• CLI 参数解析和 timeout。
• Server /status、/fetch、鉴权、错误响应。
• Extension popup 状态和手动重连消息。
• Extension tab 匹配规则：URL pattern 命中复用，未命中新建。
• Skill 文档是否保留 CLI 工作流和“不使用 MCP”的约束。
• 业务脚本的关键文本抽取逻辑，例如日志型告警抽样日志。

长期运行方式

本地开发：

cd <local-project-path>
npm start

Docker 常驻：

docker build -f server/Dockerfile -t browser-fetch-bridge-server .
docker run -d --name browser-fetch-bridge-server \
  --restart unless-stopped \
  -p 37891:37891 \
  -e BROWSER_BRIDGE_TOKEN=<bridge-token> \
  browser-fetch-bridge-server

Docker 内部使用 BROWSER_BRIDGE_HOST=0.0.0.0，本地直接运行仍默认监听 127.0.0.1。

安装到 Codex 的流程

本次插件通过个人 marketplace 暴露给 Codex：

<plugins-path>/browser-fetch-bridge -> <local-project-path>
<agents-config-path>/plugins/marketplace.json

插件 manifest 要保留：

{
  "name": "browser-fetch-bridge",
  "skills": "./skills/"
}

不要恢复 mcpServers。

验证清单

每次调整后至少运行：

cd <local-project-path>
npm test
node --check server/service.js
node --check server/ws-bridge.js
node --check cli/browser-fetch-bridge.js

人工验证：

• Chrome extension 已加载 unpacked。
• popup 能展示 proxy 状态。
• Reconnect 按钮可触发立即重连。
• status 能看到 extension connected。
• fetch 能在目标 tab 的登录态下拿到接口数据。
• 新业务 skill 的结果文件可复查，且能追溯输入时间范围和接口调用统计。

反模式

• 把具体业务系统逻辑写进 extension。
• 在 server 中解析业务 response。
• 让 extension 执行任意 JS。
• 保存 tab.id 并假设下次仍有效。
• 让 Codex 直接依赖 MCP tool，而不是通过 CLI 调常驻服务。
• 只产出总结，不保留本地可复查报告。
• 把抽样日志和告警详情混在一起，导致后续无法追溯。

关联

• 00-Daily/笔记工作流
• 05-Maps/知识库总览
• 04-Archives/Work/告警运维
• 04-Archives/Work/故障分析定位工具

可用于

• 需要 Chrome 登录态的内部 API 抓取。
• 告警按业务标识/指标汇总。
• 日志型告警抽样日志抓取。
• 将某个内部系统的浏览器操作沉淀为 Codex skill。
• 把一次性排查流程升级为可复用自动化。

后续行动

• 为常用业务系统补充独立业务 skill，而不是扩展通用 bridge。
• 给生产 token 和本地开发 token 做更明确的运行说明。
• 如果业务 skill 增多，新增一张 browser-fetch-bridge 使用地图。